/**
 * Software License, Version 1.0
 * 
 * Copyright 2003 The Trustees of Indiana University.  All rights reserved.
 * 
 *
 *Redistribution and use in source and binary forms, with or without 
 *modification, are permitted provided that the following conditions are met:
 *
 *1) All redistributions of source code must retain the above copyright notice,
 * the list of authors in the original source code, this list of conditions and
 * the disclaimer listed in this license;
 *2) All redistributions in binary form must reproduce the above copyright 
 * notice, this list of conditions and the disclaimer listed in this license in
 * the documentation and/or other materials provided with the distribution;
 *3) Any documentation included with all redistributions must include the 
 * following acknowledgement:
 *
 *"This product includes software developed by the Community Grids Lab. For 
 * further information contact the Community Grids Lab at 
 * http://communitygrids.iu.edu/."
 *
 * Alternatively, this acknowledgement may appear in the software itself, and 
 * wherever such third-party acknowledgments normally appear.
 * 
 *4) The name Indiana University or Community Grids Lab or NaradaBrokering, 
 * shall not be used to endorse or promote products derived from this software 
 * without prior written permission from Indiana University.  For written 
 * permission, please contact the Advanced Research and Technology Institute 
 * ("ARTI") at 351 West 10th Street, Indianapolis, Indiana 46202.
 *5) Products derived from this software may not be called NaradaBrokering, 
 * nor may Indiana University or Community Grids Lab or NaradaBrokering appear
 * in their name, without prior written permission of ARTI.
 * 
 *
 * Indiana University provides no reassurances that the source code provided 
 * does not infringe the patent or any other intellectual property rights of 
 * any other entity.  Indiana University disclaims any liability to any 
 * recipient for claims brought by any other entity based on infringement of 
 * intellectual property rights or otherwise.  
 *
 *LICENSEE UNDERSTANDS THAT SOFTWARE IS PROVIDED "AS IS" FOR WHICH NO 
 *WARRANTIES AS TO CAPABILITIES OR ACCURACY ARE MADE. INDIANA UNIVERSITY GIVES
 *NO WARRANTIES AND MAKES NO REPRESENTATION THAT SOFTWARE IS FREE OF 
 *INFRINGEMENT OF THIRD PARTY PATENT, COPYRIGHT, OR OTHER PROPRIETARY RIGHTS. 
 *INDIANA UNIVERSITY MAKES NO WARRANTIES THAT SOFTWARE IS FREE FROM "BUGS", 
 *"VIRUSES", "TROJAN HORSES", "TRAP DOORS", "WORMS", OR OTHER HARMFUL CODE.  
 *LICENSEE ASSUMES THE ENTIRE RISK AS TO THE PERFORMANCE OF SOFTWARE AND/OR 
 *ASSOCIATED MATERIALS, AND TO THE PERFORMANCE AND VALIDITY OF INFORMATION 
 *GENERATED USING SOFTWARE.
 */
package cgl.narada.service.client;

import cgl.narada.matching.Profile;
import cgl.narada.service.ServiceException;
import cgl.narada.service.qos.ConsumerConstraints;
import cgl.narada.service.replay.ReplayRequest;
import cgl.narada.service.replay.ReplayServiceListener;
/**
   The event consumer provides a host of functions for clients to 
   consume events. These include subscription to profiles and also the
   specification of QoS constraints that an event must satisfy prior to
   delivery. The consumer also includes several utlity functions among them
   are the ability to retrieve the number of events received at this consumer.

   @author Shrideep Pallickara
   $Date$
   $Revision$

 */


public interface EventConsumer {
  
  /** Retrieve the entity identifier */
  public int getEntityId();

  /** Retrieves the number of events routed by this event consumer */
  public int getNumberOfEventsReceivedSoFar();


  /** Retrieves the time elapsed (in milliseconds) since the last event was 
      received on this consumer */
  public long getTimeElapsedSinceLastEvent();


  /** Checks to see if a consumer constraint has been registered for 
      a given profile */
  public boolean hasConsumerConstraints(Profile profile)
    throws ServiceException;


  /** Verify if the specify QosConstraints can indeed be satisfied. This 
      method will true if there aare no specified Qos associated with the
      profile. */
  public boolean canSatisfyQosRequirements(Profile profile)
    throws ServiceException;
    

  /** Retrieves the ConsumerConstraints for a given profile */
  public ConsumerConstraints getConsumerConstraints(Profile profile) 
    throws ServiceException;
  
  
  /** Create consumer constraints associated with a certain profile */
  public ConsumerConstraints createConsumerConstraints(Profile profile)
    throws ServiceException;



  /** Gets a list of profiles managed by the consumer */ 
  public Profile[] getListOfManagedProfiles();
  
  
  /** Sets the event listener for the profiles managed by this consumer */
  public void setNBEventListener(NBEventListener nbEventListener)
    throws ServiceException;

  /** Gets the event listener for the profiles managed by this consumer */
  public NBEventListener getNBEventListener();
  

  /** Sets the notification listener for the profiles (and the specified 
      Qos constraints) managed by this consumer */
  public void 
  setNBNotificationListener(NBNotificationListener nbNotificationListener)
    throws ServiceException;
  
  
  /** Subscribe to a profile and register a listener to receive events
      conforming to the specified constraint*/
  public void subscribeTo(Profile profile) throws ServiceException;
  
  
  /** Unsubscribes a profile. If there is a registered QosEnablerAndSpecifier
      for this profile, it is also disabled.*/
  public void unSubscribe(Profile profile) throws ServiceException;
  
  
  /** Subscribe to a profile, but request that the event satisfies some 
      QoS constraints prior to delivery. This subscription may trigger a 
      discovery request and based upon the responses or lack thereof the 
      subscription propagation may succeed or not. This method requires that
      a NotificationListener be registered prior to activating the profile.*/
  public void subscribeTo(Profile profile, 
			  ConsumerConstraints consumerConstraints)
    throws ServiceException;
  
  
  /** This is called by an entity to recover from failures or prolonged
      disconnects */
  public long recover(int templateId, NBRecoveryListener recoveryListener) 
    throws ServiceException;

  /** Initiate replay based on the created replay request */ 
  public void initiateReplay(ReplayRequest replayRequest,
			     ReplayServiceListener replayListener) 
    throws ServiceException;

}

